Archive Magazine CD 1995/Archive Magazine CD 1995.iso/discs/prog_disc/volume_8/issue_06/risc_os/AppGuide

Text File | 1988-12-12 | 52.5 KB | 1,121 lines

Applications Authors' Guidelines
================================

10-Nov-88: WRS: wording changes to description of application directories
                remarks about setting memory area sizes, esp. the screen.
                improved remarks about dragging.
                various small typos corrected.
10-Nov-88: WRS: misc remark about negative monotonic time added.
12-Dec-88: WRS:
  Various minor typos corrected.
  Data transfer protocol notes removed to separate document.
  Paragraph about why to use true colours added.
  Paragraph about ADJUST on close icon added.
  Section about data interchange added.
  Remark about errors from Wimp_Poll added.
  Remarks about version numbers rationalised.
  Paragraph about interactive help added.
  Paragraph about graphics printer drivers added.

The overall design of the desktop environment within this version of
Archimedes has advanced considerably from Arthur 1.20. Here are various
notes about how the facilities should be used, and the principles that
shaped their design.

These notes are of interest to ALL applications authors. Some authors may
feel that they are not interested in window systems and that they are not
appropriate to their particular application. The functionality and
usefulness of the RISC OS desktop is such, however, that they will soon find
most of their users spending most of their time within the desktop
environment. Thus it will have a considerable influence on what typical
users understand.

General principles
------------------

CONSISTENCY. What the multi-tasking Wimp emphasises is that applications
work *together* for the user of the machine:

   They cooperate in sharing the machine.
   They look harmonious
   Their user interfaces are similar.
   The whole is more important than a single application.

When porting applications into the desktop environment, check that they work
well with the existing applications and utilities. Strive to ensure that the
habitual user of the desktop environment and the Welcome Stuite applications
will find your program easy to use, and natural to learn.

QUALITY. It is much better to write a small program that does something
simple, and does it well, than a sprawling mass that crashes occasionally.

RESPONSIVENESS. Archimedes is an extremely fast machine, and this speed
can be used to make the machine easier to use and more productive. The
system software has been written very carefully so that all of this
performance is delivered to be used by the application, rather than being
swallowed up within the operating system. Fast, smooth scrolling and redraw
are worth striving for as they make effective and productive use of an
application much easier.

COLOUR. Covering a wide range of screen modes can seem troublesome when
constructing an application, but allows a wide price-range for the end user,
who can choose between resolution and cost. Animated bright colour graphics
can help make a program easier to understand and to use. Not relying on
screen size allows your program to move easily to new better screens and
modes when they become available.

EASE OF USE. This is what window systems are about most of all.
All of the various elements described here are ultimately designed to
make the computer easier and more pleasant to use, over a wide range
of user experience and practice.
  Easy to learn
  Easy to re-learn
  Easy to use productively
These things can conflict with each other, and with other things (e.g.
system cost, program size, program development time, backwards
compatibility). Design is not easy, and not all users agree.

Specific features of the Archimedes desktop environment:

Pop-up, context-sensitive, hierarchical menus. These provide rapid and
convenient access to a wide selection of commands without continuously
occupying screen space, and represent a considerable step forwards from the
single-level, pull-down menus of other systems.

Control of multi-tasking and of memory. The Archimedes desktop envronment
makes it easy to understand which applications are using memory, and how to
get more. The memory-mapping hardware of the Archimedes means that issues
about fragmentation of free space are overcome, compared to some other
task-swapping systems. Desktop utility programs can be loaded and unloaded
at will during the use of a large application, making small utilities
considerably more useful than in other systems (where they often have to be
loaded in at system startup, and cannot then be loaded or unloaded without
resetting the machine).

Terminology
-----------

Remember that the primary users of RISC OS are users and not programmers:
consistent terminology, and the avoidance of jargon, are important in order
to make RISC OS friendly. Because Archimedes is not totally a desktop machine
some jargon inevitably slips through, but this should always be minimised.

Mouse terms:
  press - press a button down
  release - release a button
  click - press and release
  drag - press, move the mouse
  double click - press, release, press, release
  choose - what you do to a menu entry
  type - what you do to keys on the keyboard
It is a common fault to confuse "press" and "click", and to talk about
"selecting" menu entries.

Files
-----

The model of files and filing systems presented within the RISC OS desktop
is that files are always manipulated by their full path-name, including the
name of the filing system, disc, etc. This gives each file in the system a
unique name. There is no concept of "current directory". Every effort is
made to ensure that people never have to type a full path-name, but they do
have to see and (approximately) understand them.

Heavy use is made of the types of files. All files should be typed and
datestamped, rather than being of the load/exec form from the old BBC
world (but be prepared to meet these, and respond correctly).

Do not refer to, or rely on, the setting of the current directory.

NEVER build absolute drive numbers or absolute file names or absolute
filing system names into your program. Check your program working from
floppy, winchester, and econet, and ensure that installation is easy.

See below for rules about loading and saving files in programs.

Resource files
--------------

Applications in the multi-tasking world are typically represented as a
directory whose name begins with "!". The Filer provides various mechanisms
to help such applications, so that the program and its resources can be
treated as a single unit and installation etc. is easy.

Resources of any form can be held within an application directory. If an
application is intended for international use then all textual messages
within the program should be placed in a separate text file, so that they
can be replaced with those of a different language. It may be unhelpful
to read such messages one by one, however, as this forces the user of
a floppy-based system to have the floppy containging the application
permentantly in the disc drive. Error messages should all be read in
when the application starts up, so that producing an error message
does not cause an insert-floppy message to appear first.

Resources may also be written by the program during the course of execution.
For instance, if an application has user-settable display options or state
which should be preserved from one invokation of the program to another then
saving it within the application directory means that the user does not have
to worry about separate files containing such data. As a source of
user-settable options this technique is preferable to reading an environment
string, since with the latter system the user has to understand how to set
up a boot file.

Some resources are of general interest to more than one program. Typical
examples include fonts, and modules that provide general facilities. Such
resources should be placed in the !System application, whose !Boot sequence
sets a variable <System$Path>, or in a separate application such as !Fonts.
It should be noted that the use of shared resources makes applications
slightly harder to install, so check carefully that error messages are
helpful if the shared resources cannot be located.

The rules above may break down for large applications. Some applications
occupy more than one floppy disc, with swapping required during operation.
It is difficult to give precise guidelines for such programs in general
terms, because their requirements vary so widely. The rules above, however,
will be used for many smaller programs and so will be reasonably familiar to
users. Larger programs should be designed and organised to fit within the
same general philosophy, so that users find them easy to install,
understand and operate.

The key resource names that are built in to the system are as follows.
The application directory is presumed to be called !Appl in the examples
below.

!Appl.!Boot - this is the name of a file which is run when the application
directory is first "seen" by the Filer. It is usually an Obey file (see
documentation on the Obey module). Typical actions include:

(1) *IconSprites the !Appl.!Sprites resource file.
This is done automatically if there is no !Boot file.

(2) Set a run-type for data files controlled by this application.

(2) Set a type name for data files controlled by this application.

The Filer only does this if the sprite !appl does not already exist in the
Wimp sprite pool (sprite names are lower case). This prevents repeated
delays from re-executing !Boot files (or even re-examining application
directories). However, it relies on the various applications seen by the
Filer having unique names, e.g. if you have more than one !System directory
then only the first one "seen" will be used.

!Appl.!Sprites - this is the name of a sprite file. For an application
directory !Appl this can provide a sprite !appl which should be used by the
Filer, and also a sprite sm!appl for use in small-icon displays. It can also
provide sprites that relate to data files controlled by this application, in
small and large form (using sprite names file_xxx and small_xxx, with xxx
being the hex identity of the file type). See below for rules about the
appearance of sprites.

!Appl.!Run - this is the name of a file which is run when the application
directory is double-clicked. It is usually an Obey file. Typical actions
include:

(1) Execute !Boot - this will usually have been done already, but in the
presence of multiple applications with the same name the !Boot file of
a different one may have been seen first.
  Example:   Run <Obey$Dir>.!Boot

(2) Call *Wimpslot to ensure that there is enough memory free to start the
application.
  Example: *Wimpslot 150K 150K
Many applications know exactly how much memory they should be loaded with,
and manage to acquire more memory (often without the knowledge of the
language system underneath) by calling SWI Wimp_SlotSize. Paint/Draw/Edit
all maintain shifting heaps above the initial startup limit, ensuring that extra
memory is always given back to the central system when it is not needed.
Applications can also arrange to have the user control dynamically how
much memory they should have, by dragging the relevant bar in the Task Manager
display.

(3) If system resources are used then ensure that System$Path is defined,
and produce a clean error message if it is not.
  Example: If "<System$Path>" = "" Then Error System resources cannot be found

(4) Ensure that any soft-loaded modules are present that the application
requires, using *RMEnsure.
  Examples:
            RMEnsure SharedCLibrary 0 RMLoad System:modules.CLib
            RMEnsure ColourTrans 0.10 RMLoad System:Modules.Colours
            RMEnsure ColourTrans 0.10 Error You need ColourTrans 0.10 or later
If your call to RMEnsure can load a module from outside your application
directory then you should call it twice, to ensure that the newly loaded
module is indeed recent enough.

(5) Loading a module cannot steal memory from the "next" slot set up by
wimpslot, so the memory set up by the *WimpSlot will still be valid - that
is why *WimpSlot must be called before loading modules (e.g. in case all of
free memory is in the next slot when the process starts). However, some
applications wish to ensure that there is also some "free" memory after they
have loaded, for example if they use the shifting heap strategy outlined in
(2). Such applications may now at this point call *WimpSlot again, with a
slightly smaller slot setting, to leave just the right amount in the next
slot while at the same time ensuring that there is some memory free.

(6) Set an environment variable from <Obey$Dir> If you wish to access any
other resources at run-time. This will give you the full path-name of your
resource directory.

(7) Run <Obey$Dir>.!RunImage. This is the conventional name of the  actual
program. It is also used by the Filer to provide the datestamp of an
application in full-info mode.

It should be emphasised that the presence of multiple applications with
the same name should be thought of as an unusual case, but should not cause
anything to crash. Also, complain cleanly if your resources can no longer
be found after program startup.

There are, of course, variations on this startup sequence. It's quite common
to bundle up existing applications so that they have an icon, and start neatly
from the desktop environment. When doing this, note that it's possible to
set the sizes of other memory areas in the machine using OS_ChanageDynamicArea.
One point to note here is that the screen must not be allowed to grab memory
from the "Next" slot - this can cause a crash. It is easily avoided by setting
the next slot to 0 while setting up screen mode etc., e.g. see the startup
sequence for !Lander which sets the next slot to 0 before setting the screen
mode.

Memory
------

In a multi-tasking environment, memory should be used sparingly. Most simple
applications require a fixed amount of memory, which can be arranged using a
!Run file that specifies exactly the right *WimpSlot size.

Applications with more complex requirements can arrange to call
Wimp_SlotSize at run-time to take (and give back) memory. Basic programs
may use the new END= construct. C programs should call Wimp_SlotSize
directly, the language run-time library (and malloc) will be entirely
unaware that this is happening and so you must organise the extra memory
yourself. A common way of doing this is to provide a shifting heap in which
only large blocks of variable size data live. By performing shifting on this
memory, pages can be given back to the Wimp when documents are unloaded.

DO NOT RECONFIGURE THE MACHINE. DO NOT KILL OFF MODULES IN ORDER TO
GET MORE WORKSPACE. Such sequences are quite likely to be hardware-dependent
and OS-version-dependent.

305 owners who wish to upgrade to RISC OS are warned that they should
upgrade to 1MB machines first.

Graphics
--------

Programs should work in all screen modes in which the Wimp works. Read the
current screen mode rather than setting it when your program is loaded, and
read system variables to obtain resolution, aspect ratio etc.  instead of
building these into the program. Use Wimp_SetColour rather than GCOL (or
ColourTrans, see below). At the very least, the program should not crash in
inappropriate modes, but should display a message in your window, e.g.
"256-colour mode only", as appropriate. Mode 0 is not usually useful, but
worth making work if you possibly can, for users with big monochrome screens
(mode 23). Also, try a square pixel mode (e.g. mode 9). Also check in modes
13, 15, 16, 18, 19, 20.

Think of an OS-unit as being a constant unit of measurement, rather than a
fraction of the width of the screen (as was the model in the old BBC world).
The standard assumption is that there are 180 OS-units to the inch, even
though this may in fact vary between physical screens. "device-independent"
should be interpreted as meaning "the same absolute size in any mode" rather
than "the same number of pixels" or "the same fraction of the screen".

Do not change the palette, but read and use the existing one.

Mode 16 is highly non-square, i.e. the aspect ratio is wrong. Do
not try to correct for this automatically, it is an inevitable consequence
of trying to fit a great deal of text onto a standard monitor.

There is a broadcast when the mode changes, so any mode-specific data can be
changed at that point. Programs uninterested in colours must also check
operation in 256-colour modes, e.g. some XOR-ing tricks do not work quite
the same. For instance, the Wimp paints the caret (using XORing so that it
can be easily unpainted again) with Wimp colour 11 (red) XOR'd with the
colour code for Wimp colour 0 (white). This ensures that it always appears
red when on a white background.  The Clock application uses a similar trick
for the second hand of the clock. As another example, Edit uses XORing with
Wimp colour 7 to indicate its selection, but uses redraws in 256-colour
modes.

In 2-colour modes the Wimp uses ECFs (dot patterns) for Wimp colours 1-6
(grey levels). Note that certain XOR-ing tricks do not work on these, and
that use of Wimp_CopyBlock can cause alignment problems for the patterns.

Many programs choose to render graphics in "true" colours, and use the
current palette to give as close an approximation as possible to the colour
they intend. This approach to colour has the enormous benefit that it is not
tuned to the limitations of today's hardware. The palette utility produces
another broadcast when the user changes the palette settings, allowing such
programs to repaint for the new palette. A soft-loaded module called
ColourTrans is available (used by Paint and Draw) to give the closest
setting possible to a given RGB value.

When should an application use true colours, and when should it use Wimp
colours? As a general rule, any colours stored in documents and used when
printing, should be true colours. Wimp colours are a convenient selection of
contrasting colours for use when you don't really care what actual colours
get used, as long as the result looks pleasant. True colours should be used
whenever an object's colour really matters. The colours stored in Draw
files, for instance, are true colours because the file has a precise meaning
(of an image rendered on an abstract device) regardless of the current
screen or palette settings.

The graphics printing facilities provided with RISC OS are based on the
assumption that the same code should be used for redraw as for printing.
There are various limitations in the printer drivers, all of which
constitute good practice when writing to the screen too. Note that as a
general rule, the use of the Draw module instead of Plot codes for line and
area graphics means that a much better model of device-indpendent graphics
is available.

A technique used on some systems is to remember the bitmap behind a menu or
dialogue box when popping it up, to make removing it faster. This is not
possible in a multi-tasking world because a window from a separate task may
be changing in background. Rather than doing this, concentrate on making
redraw FAST. One available technique for this is to use sprites to remember
the contents of a window which are difficult to redraw quickly.

Another important technique for speeding redraw is the use of source-level
clipping. During redraw and update, the Wimp always informs the application
program of the current clipping rectangle. The redraw of icons, and of
objects in Draw, is fast because this rectangle is used as a rapid test
for the rejection of many redraw operations.

Do not use the system sprite pool in product programs, build a user one. The
system sprite pool is present in Archimedes for backwards compatibility with
the Master, and to help the construction of very simple programs.

Some program developers feel very strongly that a program should be able to
take over the entire screen, without any scroll bars etc. It is perfectly
possible for a program to do this and still benefit from the multi-tasking
environment, as long as this is treated as a speicific mode of operation
(chosen by a menu entry saying "Fill screen", for instance), and the program
can also operate in a window. This facility can easily be implemented by
opening a window the size of the screen, on top of all others. Some programs
may even have special properties that only operate when in this mode, e.g.
animation implemented using direct writing to the screen. The desire for
this mode of operation, however, should not (alone) lead you to abandon the
multi-tasking world entirely.

The Mouse
---------

The mouse has three buttons, called SELECT (left), MENU (middle) and ADJUST
(right).

When a "selection model" is being used for a set of objects, the
button actions should follows those of the Filer, Edit and Draw,
namely:
  SELECT is used to make an initial selection
  ADJUST is used to toggle elements in and out of this selection
    (talk about "adjusting" the selection)
This is the origin of the names for the buttons.

Always use SELECT as the "primary" button of the mouse, used for pointing at
things, dragging etc. ADJUST is used for less common or less obvious
functions, or for slight variations and speedups. If you have no useful
separate operation in any particular context, then make ADJUST do nothing
rather than duplicating the functionality of SELECT: this is all part of
training the user to use SELECT first.

Another technique for speedups and variations on mouse operations is to
look at the setting of the shift key when the mouse event occurs. Such
combinations should never be "necessary" to the operation of a program,
e.g. a user experimenting with your program should not be expected to
try all such combinations.

The Wimp detects double-clicks, typically used to mean "open object". It
should be noted that a double click causes a single-click event to be sent
to the program first. Some other systems avoid this, which may appear to
simplify the task of programming but leads to reduced responsiveness to
mouse operations.

Menus
-----

Menus are accessed via the middle mouse button, referred to as MENU.

As a general rule an application should provide a single menu tree within a
window, rather than a collection of little menus that require the user to
point at a specific place in the window before pressing MENU. The problem
with the latter approach is that it is hard for the user to determine the
complete set of commands available.

(Aside: this is known as the "closure" principle. The user should be able
to guess what your program can do, and discover fairly rapidly what it
can't do, without having to search everywhere for hidden menus etc.)

It is reasonable for entries in the menu to be context-sensitive. In general
such portions of the menu depend either on the object indicated when MENU is
clicked (e.g. in the Paint file window), or on a "selected" object or
objects (e.g. in Edit).

Standard colours for menus:

  title is black(7) on grey(2)
  body is black on white(0)
  items 44 OS-units high
  no separation between items
  text is left-justified (except for keyboard equivalents, see "Keystrokes")

The title says "Appl" (the application name) rather than "Appl Menu". Entries
have initial letters capitalised and are in lower case otherwise.

Try not to make non-leaf menus too wide: reducing the horizontal travel
necessary helps rapid selection in nested menus. Open the menu initially 64
OS-units to the left of the actual click, in order to aid this.

Do not grey out non-leaf menus. This helps the user to understand
the complete set of operations available at any time.

Click on a non-leaf should have no effect (other than removing the menu
tree) or should duplicate functionality that is available elsewhere.

Clicking SELECT or MENU on a menu entry should should choose the
current menu item, closing the menu tree.

Clicking ADJUST on a menu entry should cause the relevant action to be
performed, but the menu to remain. Flags, ticks, grey items etc. on the menu
tree should reflect the new state after the action being performed. This is
achieved in the following way. On a menu click, the application should call
Wimp_GetPointerInfo and decide if ADJUST is being held down. If it is,
re-open the same menu structure at the same location, and the Wimp will
ensure that exactly the same positions are assumed by the various levels of
the menu. This rule should only be broken if the object being referred to is
destroyed by the action of the menu click.

(Note that you should call Wimp_GetPointerInfo BEFORE doing the operation
chosen by the user from the menu, but the menu re-opening must be done AFTER
the operation, so that any flags have been updated.)

Clicking outside the menu tree results in the menu being closed before the
click event occurs. This allows the user to ignore the menu tree if no menu
operation is required. To cancel the menu tree, the user clicks on the
background. ESC also cancels the menu tree.

Menus produced from the icon bar should be moved up a little before opening,
so that the relevant menu bar entry is still visible. The base of the menu
should be 96 OS-Units from the bottom of the screen. The menu should
be horizontally aligned so that the left hand edge of the menu is 64 OS-Units
to the left of the point where the mouse click occurred.

Keyboard equivalents should be shown on the menu items for which they are
short cuts. See the section named "Keystrokes".

Dialogue Boxes
--------------

The simplest way to provide dialogue boxes is as leaves of the menu tree. If
the necessary windows are permanently created and linked to the menu data
structure, then the Wimp will handle all opening and closing automatically.
Alternatively, the menu tree can be so arranged that the application is
informed when the dialogue box is being opened, this allows any computed data
to be delayed until the last minute. For a large program with many dialogue
boxes this is preferable, as the Wimp has a limit on the number of windows in
existence between all tasks.

This form of dialogue box can be visited by the user without clicking on mouse
buttons, just like traversing other parts of the menu tree. This is possible
because redraw on Archimedes is typically much faster than on previous
systems, so popping up the dialogue box and then removing it does not cause a
significant delay.

Colours for dialogue boxes:

  title is black (7) on grey (2)
  title highlight colour is grey (2)
  body is black (7) on grey (1)
  writable fill-in fields are black (7) on white (0), with a border.
  action buttons are black (7) on cream (12), with a border.
Dialogue boxes match the colouring of menus, to show that they are "part of
the menu tree".

Dialogue boxes do not have close boxes.

Provide a dialogue box that fully identifies the program, version etc. that
is running. This is usually at the very top of the menu tree, e.g. the first
leaf of the first branch. The leaf-name "Info" should be used to identify this
within the menu tree, and the title "About this program" should be used
for the dialogue box. See later remarks about program versions.

If a menu operation leading to a dialogue box has a keyboard shortcut,
Wimp_CreateMenu should be used to initially open the dialogue box rather
than Wimp_OpenWindow (athough Wimp_OpenWindow should still be used in
response to Wimp_Poll (OpenWindowRequest). This will ensure that it has the
same behaviour concerning cancellation of the operation etc. as when
accessed through the menu tree.

There are various common forms of icon that occur within dialogue boxes,
the most common forms are described here to improve consistency
between applications.

Writable Icons
--------------

Writable icons are used for various forms of textual fill-in field. They
provide filter strings so that specific characters can be forbidden,
alternatively arbitrary filtering code can be added to the application to
ensure that only legal strings (within this particular context) are entered.

A writable icon should have a black border and a white background.

Code should be added to the handling of each dialogue box for the following
keystrokes. It's not possible for the Wimp to do this, because it doesn't
know the right ordering to use.

down-arrow: move to the next writable icon within the dialogue box,
or to the first if currently at the last.

up-arrow: move to the previous writable icon within the dialogue box,
or to the last if currently at the first.

RETURN: move to the next writable icon within the dialogue box, or perform
the default "GO" operation for this dialogue box if currently within the last
writable icon.

When moving to a new writable icon, the caret should be placed at the
end of the existing content of the icon.

Action Icons
------------

This term refers to "buttons" on which the user clicks in order to cause
some event to occur, typically the event for which the parameters have just
been entered in the dialogue box.

An action icon should have black (7) writing, a border, and cream (12)
background.

The best icon to use is button type 7 ("menu"), with ESG not zero.
This will cause the button to invert when the pointer is over it (like
a menu item).

It is sometimes appropriate to provide keyboard equivalents for action
buttons. For instance, if the dialogue box is available via a function key
as well as on the menu (see "Keystrokes") then adding key equivalents for
action icons may mean that the entire dialogue box can be driven from the
keyboard. A conventional use of keys is:

RETURN in the last writable icon. Go, perform the obvious action initiated
by filling in this dialogue box.

ESCAPE. Cancel the operation, remove the dialogue box. Note that ESCAPE is
dealt with by the Wimp automatically in this case.

Function keys F1, F2, F3. If the action icons are arranged positionally
at the top or bottom of the icon in a simple row, then define F1... as
positional analogues of the action buttons, e.g. F1 activates the
left-most one, F2 the next, etc.

Option Icons
------------

This term refers to "switches", which can either be on or off.

The best icon to use is a text-and-two-sprites one. The text is
left-justified and has the validation string "soptoff,opton" with the optoff
and opton sprites within the default Wimp pool. This generates a box to the
left of the text, with a star within it if the option is on (e.g. the icon
is selected). The button type is 11.

Radio Icons
-----------

This term refers to a set of options where exactly one out of a set of
icons can be set.

The text-and-two-sprites form is again best, using the sprites "radiooff"
and "radioon" from the default Wimp pool, and an ESG to force exclusive
selection.

Static Dialogue Boxes
---------------------

A static dialogue box is opened using Wimp_OpenWindow rather than
Wimp_CreateMenu. A static dialogue box matches normal ones in colours, but
has a close box.

One common form of use is a "tool" dialogue box. This typically consists
entirely of action icons, and is used in preference to a submenu because the
typical mode of use is of rapid switching between the tool box and the
pointer. An example is the colour and tool windows in Paint. These are
activated (for a given sprite) using menu entires "Show colours" and
"Show tools".

Another reason to use a static dialogue box is that it may be appropriate
to attach menus to a dialogue box.

Another reason is that it's not possible to drag an icon into a normal
dialogue box from another application, because as soon as the drag starts
the menu tree is cancelled (see the sections on loading and saving files).

Keystrokes
----------

When you gain the caret, do not automatically pop above other windows in the
stack. Also, a window should generally only gain the caret if the user
clicks inside it - the exceptions being menus and dialogue boxes, which
should give the caret back to the previous owner when they close - this is
done automatically by the Wimp for menus and non-static dialogue boxes.

If you receive a keystroke that you do not understand or use, hand it back
to the Wimp using Wimp_ProcessKey. This allows other windows to provide
hot-key operations that work anywhere, it also allows the Wimp to do
function key expansion in the last resort.

Keyboard speedups for menu operations are useful to expert users. Reminders
of their existence should be placed right-justified in the relevant menu
entry, as in the following examples:

     (ctl-X)           control character
     (f3)              function key
     (shf-f3)          shifted function key
     (ctl-f3)          control function key
     (ctl-shf-f3)      control shifted function key
     (ctl-alt-shf-f3)  most complex example: control, alt and shift

Use function keys for most speedups. use ^Z, ^X, ^C and ~V for
operations that refer to a "selected" object or objects:

    ctl-Z        clear selection
    ctl-X        delete selection
    ctl-C        copy selection
    ctl-V        move selection

This allows the expert right-handed user to access these operations
extremely rapidly.

Use ALT as a shifting key rather than as a function key. Different forms of
international keyboards have standardised the use of ALT for the entering of
accented characters.

Do not forbid the use of top-bit-set characters in your program, and many
standard accented characters are available there. These characters are
clearly distinguished from the function keys by the Wimp.

Due to their frequent polling of the Wimp, window'd programs do not normally
need to use escape conditions. The Wimp sets the escape key to generate an
ESC character. If you perform a long calculation without calling Wimp_Poll,
you may set the escape action of the machine to set escape conditions (using
*FX 229,0), as long as you set it back again (using *FX 229,1 and then *FX
124) before calling Wimp_Poll.

Version Numbers
---------------

Significant applications typically have an Info box of a standard format,
that gives the version number of the application being used. Provide it at
the top of the menu in the icon for your program. Copy closely the form of
dialogue box used in the Welcome Suite applications.

Very small applications need not have this, but all programs should also be
identifiable by a version number on the first line of their !Run file.

Editors
-------

An editor is a program that presents files of a particular format as
abstract objects which the user can load, edit, save, and print. Text
editors, word processors, spreadsheets, draw programs are all editors in
this context. Their data files are referred to as documents.

Each document being edited is typcially displayed in a window. Such
windows are referred to as "editor windows".

Most editors, for each document currently being edited, record whether
the user has made any adjustments yet to the document. This is known
as an "modified flag".

The title of an editor window is conventionally the filename of the current
document, centred, with a postfix " *" if modified. The minimum size can be
set to ensure that this does not restrict the window's minimum size.. Use
"<untitled>" if the document has not yet been saved or loaded. If there are
multiple views of the same document then postfix " %n" to this, where %n
is the number of views of this document that exist.

Standard editor window colours:
  title fore is black (7)
  title back is 2
  title hilight is 12             (input focus indication)
  scroll outer is 3
  scroll inner is 1

Some editors are capable of editing several documents of the same type
concurrently, while others can edit only one object at a time. Being able
to edit several documents is frequently useful, and removes the requirement
for multiple copies of the program to be loaded. Such programs are
referred to here as multi-document editors. Edit, Draw and Paint
are all multi-document editors, while MusicEd and FormEd are not.

Editors use RISC OS file types to distinguish which application belongs to which
file. Their !Boot files should give a name, a sprite (in the Wimp sprite
pool) and a run action to such file types. File types are allocated by Acorn
ISV support.

The user interface of RISC OS concerning loading and saving documents is
rather different from other systems, because of the permanent availability of
the Filer windows. This means that there is no need for a separate
"mini-Filer" which presents access to the filing system in a cut-down way.
Although this may feel unusual at first to experienced users of other
systems, it soon becomes natural and helps the feeling that applications are
working together within the machine, rather than as separate entities.

The Icon bar
------------

Icons on the icon bar represent facilities and services available within the
computer that are offered by currently running applications. Some of these
directly represent hardware devices or filing system access points, these go
on the left of the icon bar. The rest are purely software services, and go
on the right. Each application is typically represented by just one icon.

When an editor is loaded it registers an icon on the icon bar. This icon is
typically the same as the one used to represent the application within the
Filer.

An editor typically needs two (related) icons: one for data files, one for
the application. The latter is used for the application in the Filer.
Clicking this usually creates a blank data object, or opens the current one
if your program can only edit one at a time.

Normal size for file icons, and for things on the icon bar:
  68 OS-units high
  68 OS-units wide
Icons with a different height are strongly discouraged, as they will have
their top edges aligned within the filer "large icon" display. A wider icon
is permissable, but the size above should be thought of as "standard". If
the width is greater than 160 OS-units then the edges will not be displayed
in the filer "large icon" display.

Icons are often displayed half size to save screen space. Hand-tuned
small versions of icons are usually provided.

Check the appearance of icons in 2, 4, 16 and 256 colour screen modes. Do
not assume that your customers have a MultiSync monitor. Note that icons
must not be defined in 256-colour modes (the Wimp can't cope).

Icons for files conventionally have a black border 4 OS-units wide. Icons
for devices conventionally have a grey (5) outline and cream (12) body.
Icons for applications are conventionally not square (thus requiring a mask)
and related in some way to the documents files that they edit.

Starting an Editor
------------------

The standard ways of starting an editor are:

  Either:
    Double-click on the application icon within the Filer
  Or:
    Double-click on a document icon within the Filer

The action taken in the first case is to load a new copy of the application.
The only visible effect to the user is that the application icon
appears on the icon bar.

The action in the second case is to load a new copy of the application,
to register its icon on the icon bar, to load the specified document
and to open a window onto the document. This effect typically occurs by the
activation of the run-type of the document file, which in turn will invoke
the application by name with the pathname of the document file as its single
argument.

Newly opened windows on documents should be horizontally centred in a
mode-12 screen, and not occupying the entire screen. This emphasises that
the application does not replace the existing desktop world, but is merely
added to it. Subsequent windows should not totally obscure ones that this
application has already opened, e.g. use a small offset with each new
window.

The action in the second case is modified if a multi-object editor of the
correct type is already loaded. In this case, the existing application
will notice the broadcast from the Filer that a double-click has occured,
and will open a window on the document itself. For details, see the Data
Transfer Protocol documentation.

A further way of opening an existing document is to drag its icon from the
Filer onto the icon representing the editor. In this case, a data load
message is sent by the Filer to the editor, which can edit the file. This
form is important because it specifies the intended editor precisely, for
instance if both Paint and FormEd are being used (both can edit sprite
files) then double-clicking on a sprite file could load into either.

Creating new documents
----------------------

In a multi-document editor, clicking on the editor icon on the icon bar
creates a new, blank document in a newly opened window. If arguments are
required in creating a new document, it may also be appropriate to use a
dialogue box during the course of this process. If a style sheet is required
(e.g. for a DTP program) then it may be appropriate to use a static dialogue
box, and drag the style sheet from the Filer.

The window created from the loading or creation of a document should
be no larger than the windows created by Edit, and should be in the same
position on the screen. Stagger further new windows down by 48 OS-units
for each new window, but if this would overlap the icon bar then return
to the original starting size and position. The initial size and position
of windows should be user-configurable, by setting a window in a template
file.

In a single-document editor, clicking on the editor icon on the icon bar
creates a new, blank document if there is not already a document loaded. If
there is already a document loaded, this moves the document window to the
front of the window stack, in case it has been obscured by other windows.

Editing existing documents
------------------------

To open an existing document, double-click on the document in the Filer.
This will cause a broadcast from the Filer when it's about to open
something, so if your editor can edit multiple documents it can catch this
broadcast and load the document into the existing editor.

To insert one document into another, drag the icon for the file to be
inserted into the open window of the target document. The Filer will then
send a message to that window, giving the type and name of the file dragged.
The target (if the file is of a type that can be inserted) can now read
the file. If the file is not of a type that can be inserted in this document
then the editor should do nothing, e.g. no error message is produced.

Saving documents
----------------

To save a document, provide a dialogue box as follows.

-------------------------------------
|                                   |
|              Save as:             |
|                                   |
-------------------------------------
|                                   |
|       - - - - - - -               |
|       |                           |
|                   |               |
|       |                           |
|           sprite  |               |
|       |                           |
|                   |               |
|       - - - - - - -               |
|                                   |
|  ---------------------    ------  |
|  |    <writable>     |    | OK |  |
|  ---------------------    ------  |
|                                   |
-------------------------------------

The dialog box consists of a sprite icon, a writable icon, and an action
icon. The exact dimensions should be copied from the palette utility. The
writable icon should have the caret at the end. More options may be added if
necessary, as appropriate to the document type in question.

This is the standard equivalent of the "minifinder" in other systems. If
there is no file name then invent a simple leaf name, e.g. TextFile in
Edit, so that just dragging will not cause an error.

The user can now:

(1) hit RETURN or click on OK to save in the already named file
    (clicking on the menu entry that leads to this dialogue box
     should have the same effect).
(2) edit the filename as desired using the keyboard
(3) drag the icon into a directory viewer.
(4) hit ESCAPE to cancel the operation

(1) is used when saving an already saved document. (3) is used when
specifying a destination directory for the save. (2) is used when editing
the leaf-name of the file. Typically, it is necessary to do (2) and (3) when
first saving a file, and (1) thereafter.

When (1) happens, the application should check that the proposed name does
at least contain one '.' character. This prevents a common error in
beginners, who just see the proposed leaf name, and attempt to press OK
immediately. The error message "To save, drag the file icon to a directory
viewer" should be used for this case.

When a drag happens, send a message to the window where the drag ends,
saying that you want to save the file. The window (if it is a dir viewer)
will reply with the name of the directory. Append your leaf-name to this and
save there.

If the save is succesful, update your stored name for the document
and remove the dbox: the operation is complete. Check return codes and
errors from saves.

"Save" should be interpreted as being like "save and resume" from some
other systems, e.g. after the operation the user is still editing the
same document. Save should cause the document to be marked unmodified,
unless the save was to a scrap file (see the section on data transfer).

Remember the datestamp on a loaded document. If the document is stored
without being modified, save with an unchanged datestamp. Otherwise, save
with the current datestamp and update the retained datestamp for
the document.

Saving a portion of a document (e.g. "Save Selection") may be grouped either
with other save operations, or with the Save File operation. If there are
several possible selection save formats then putting it on Save may be more
appropriate. Balancing submenus may also be an issue. Edit and Paint, for
instance, group it with other selection operations while Draw (which has
several differnt forms of Save Selection, and many other operations on the
Selection submenu) groups it with Save File.

Closing document windows
------------------------

If the user clicks on the Close icon of a document window,
and there is unsaved data, then you should pop up a dialogue box
asking:
  Do you want to save your edited file?  (if the document has no title)
or:
  Do you want to save edited file '%s'?
You can copy this dialogue box from Edit's template file. If the answer
is Yes then pop up a save dialogue box, and if the result is saved then
close the window. If the answer is No, or any cancel-menu (e.g. ESC)
occurs, then the operation is abandoned.

An additional feature that can be implemented on the close button is as
follows: if the user clicks ADJUST on the close icon then close the
document, and open the parent directory viewer (using *filer_opendir). This
is similar to the use of ADJUST on the close icon of a directory viewer: the
directory tree, and the documents within it, are thought of as a continuous
tree of information over which the user navigates. If he clicks ADJUST with
shift held down, or with the document modified, just open the parent.

Quitting editors
----------------

A Quit operation should be supplied at the bottom of the menu attatched
to the icon of an editor. If it is selected when there is unsaved data,
then ask the question:
  %n file%s edited but not saved in <prog>: are you sure you want to Quit?
(The %s should be "s" if the %n is not 1, else "".)

The same question should be asked if a desktop-closedown sequence occurs.
In such a case, if the answer is Yes, then the desktop-closedown sequence
should be restarted by sending a shift-control-f12 keystroke message to
the original sender of the desktop-closedown message.

Data interchange
----------------

One of the most powerful aspects of multi-tasking in RISC OS is the direct
dragging of data from one application to another, and its easy import and
export in a variety of formats from applications.

Think of a data format as a commitment to forwards and (if possible) backwards
compatibility. Write an extremely careful definition of your data format, and
try to build in:
    testing for the correctness of the file
    version control for the file format
    extensibility for the file format
If your application is successful and widely used then other software
authors will be tempted to write other programs that perform other
operations on the data formats that you have defined. Work hard to encourage
this! Send a copy of such a format definition to Acorn ISV support, it will
then be available to other ISVs as an embryonic de facto standard for that
particular type of data.

Do not reinvent the wheel. If there is already a data format out there to
describe what you want then use that: even if it comes from a computing
system or background that you do not intend to work with.

Miscellaneous
-------------

Do not take idle events unless you have to. They slow everything down. If
you do need to take null events, Wimp_PollIdle is preferable to Wimp_Poll,
unless the user is directly involved (eg. dragging an object) and
responsiveness is important.

If you set your own pointer shapes, use pointer 2 for them. Set back to
pointer 1 (the standard generic arrow) on a pointer-leaving-window event.
Pointers 3 and 4 are used by the hourglass.

Do not use mouse colour 2, as it behaves strangely on hi-res mono
screens (e.g. it alternates between black and transparent!).

Do not pop your window to the front when grabbing the caret, and do
not grab the caret when your window is popped to the front. You should
only grab the caret as a response to clicks within your work area.

The Wimp's drag operations are specifically for drags that must occur
outside all windows. As well as the crawling-box form they allow the use of
user-defined graphics, allowing arbitrary objects to be dragged between
windows.

If you build drag operations within your window, check that redraw works
correctly when things move in background (the Madness application is useful
for this). Also, it is important to note that such "within-window" dragging
must use Wimp_UpdateWindow to update the window, rather than drawing
directly on the screen.

If the drag works with the mouse button up then menu selection and scrolling
can happen during the drag, which is often useful. Stop following the drag
on a pointer-leaving-window event, and start again on a
pointer-entering-window event.

If the drag works with button-down, then it may continue to work if the
pointer is moved out of the window with the button still down. Alternatively
for button-down drags, you can restrict the pointer to the visible work
area, and automatically scroll the window if the pointer gets close to the
edge.

Always check all error returns from Wimp calls. This includes
Wimp_Poll, which can fail in rare circumstances.

Beware errors in redraw code, they are a common way for systems to lock up
(because the redraw fails, the Wimp asks you again to redraw, and so on). A
suddenly missing font, for instance, should not lead to infinite looping.
Check that the failure of window or icon creation does not lead you to crash
or lose data. Check cases concerning running out of space.

Do not use Wimp_CopyBlock during redraw, even if you know that the source is
visible: Wimp_CopyBlock should be used outside the redraw loop, to copy
whatever relevant areas of the window are visible, and cause
redraw-window-events for the rest. Redraw routines should be very similar
(or identical) to routines used to print graphics, for which CopyBlock (and
XOR-ing tricks) will not work.

If the user is asked to insert a floppy disc and hits "Cancel", you get
an error "Disc not present" or "Disc not known" from ADFS (look up
the IDs in the PRM). If you get either of these errors from an operation you
need not call Wimp_ReportError, just cancel the operation. This avoids the
user getting two error boxes in a row.

There are two clocks showing real time in the system, the hardware clock and
a centisecond timer. The two can diverge by a few seconds a day, but are
resynchronised at machine reset. For consistency, always use the
centisecond timer.

Do not have phrases like "at line 1230" in error messages from Basic
programs. "(internal error code 1230)" is preferable.

DO NOT BYPASS OS DEVICE INTERFACES AND ACCESS HARDWARE DEVICES DIRECTLY! DO
NOT PEEK AND POKE PAGE ZERO LOCATIONS, OR KERNEL WORKSPACE! Such tricks may
well NOT WORK on future machine and operating system upgrades. Acorn will
pursue a policy of continuous improvement and expansion for its Archimedes
product-line: build your software to last.

The File dialogue box provides useful information about a file being
edited. Provide it at the top of the menu in a file window, or within a
Misc submenu there (if there are other miscellaneous menu entries to
collect).

Filenames of up to 255 characters should work. Longer filenames should
not crash your application.

When using Wimp_PollIdle, remember that monotonic times can go negative
(e.g. wrap round in a 32-bit representation) after around six weeks.
So when comparing two times,
    (newtime - oldtime) > 100
is a better comparison than
    newtime > oldtime + 100.
This problem caused early versions of MailMan to go wrong after six weeks of
continuous use.

Interactive help is extremely easy to provide via the !Help application:
doing so enormously increases user's confidence that all desktop
applications are working together. It may even be helpful too, particularly
to occasional users of the package who just need a little reminder of what
it does.